package jblip.resources;

import java.io.Serializable;
import java.util.Date;
import java.util.List;

/**
 * <i>Update</i> resource interface.
 * 
 * <p>
 * This resource contains all accessible data about message in the system. This
 * includes other resources, such as <i>picture</i> and <i>user</i>. See the
 * Blip documentation for details.
 * </p>
 * 
 * @author Krzysztof Sroka
 * @since 0.1
 */
public interface Update extends Serializable {
  /**
   * Get the list of pictures attached to this update (if any).
   * 
   * @return List of <i>picture</i> resources attached, or <code>null</code>
   *         if such doesn't exist.
   */
  public List<? extends Media> getAttachedPictures();

  /**
   * Get the audio recording associated with this update (if any).
   * 
   * @return Media resource representing a recording attached to this update, or
   *         <code>null</code> if such doesn't exist.
   */
  public Media getAttachedRecording();

  /**
   * Get the video associated with this update (if any).
   * 
   * @return Media resource representing a video attached to this update, or
   *         <code>null</code> if such doesn't exist.
   */
  public Media getAttachedMovie();

  /**
   * Get the path of the picture resources list attached to this update (if
   * any).
   * 
   * @see #getAttachedPictures()
   * 
   * @return Path-part of the URL containing the list of media resources, or
   *         <code>null</code> if such doesn't exist or if this update has
   *         that list attached.
   */
  public String getAttachedPicturesPath();

  /**
   * Get the path of the audio recording attached to this update (if any).
   * 
   * @see #getAttachedRecording()
   * 
   * @return Path-part of the URL containing the media resource, or
   *         <code>null</code> if such doesn't exist or if this update has
   *         that resource attached.
   */
  public String getAttachedRecordingPath();
  
  /**
   * Get the path of the video attached to this update (if any).
   * 
   * @see #getAttachedMovie()
   * 
   * @return Path-part of the URL containing the media resource, or
   *         <code>null</code> if such doesn't exist or if this update has
   *         that resource attached.
   */
  public String getAttachedMoviePath();

  /**
   * Get message body.
   * 
   * @return <i>Body</i> element of this resource.
   */
  public String getBody();

  /**
   * Get update's creation time.
   * 
   * @return Creation time of this resource, as an object.
   */
  public Date getCreatedAt();

  /**
   * Get update's creation time in milliseconds since Unix epoch.
   * 
   * @return Creation time of this resource, as an long integer.
   */
  public Long getCreatedAtEpoch();

  /**
   * Get the receiver of this update.
   * 
   * @return {@link User} resource describing the recipient of the message
   *         represented by this resource, or <code>null</code> if there is no
   *         such (ie. when this resource represents a user's status).
   */
  public User getDstUser();

  /**
   * Get login of the receiver of this update.
   * 
   * @return String representing login name of the recipient of the message
   *         represented by this resource, or <code>null</code> if there is no
   *         such (ie. when this resource represents a user's status).
   */
  public String getDstUserLogin();

  /**
   * Get the sender of this update.
   * 
   * <p>
   * <i>NOTE: the Blip API documentation states that this is an optional
   * element, and may not be included in the "update" resource. However, any
   * message has it's sender and the sender field is not included in a "update"
   * resource, when the resource is embedded in a "user" structure. Keep in
   * mind, that implementations of {@link Update} won't necessarily put this
   * information here. </i>
   * </p>
   * 
   * @return <i>User</i> resource describing the sender of the message
   *         represented by this resource, or <code>null</code> if there is no
   *         such (see above).
   */
  public User getSrcUser();

  /**
   * Get login of the sender of this update.
   * 
   * @return <i>User</i> resource describing the sender of the message
   *         represented by this resource, or <code>null</code> if there is no
   *         such (see <code>getDstUser()</code>).
   * 
   * @see #getDstUser()
   */
  public String getSrcUserLogin();

  /**
   * Get ID of this message.
   * 
   * @return ID number of this resource.
   */
  public Integer getId();

  /**
   * Get the transport of this message.
   * 
   * @return Transport definition of this resource.
   */
  public Transport getTransport();

  /**
   * Get the type of this message.
   * 
   * <p>
   * A message can be either a public status, or a directed message.
   * </p>
   * 
   * @return Type of this resource.
   */
  public UpdateType getType();
}
